home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / gaim / log.h < prev    next >
C/C++ Source or Header  |  2005-10-18  |  8KB  |  288 lines
  1. /**
  2.  * @file log.h Logging API
  3.  * @ingroup core
  4.  *
  5.  * gaim
  6.  *
  7.  * Gaim is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _GAIM_LOG_H_
  26. #define _GAIM_LOG_H_
  27.  
  28. #include <stdio.h>
  29.  
  30.  
  31. /********************************************************
  32.  * DATA STRUCTURES **************************************
  33.  ********************************************************/
  34.  
  35. typedef struct _GaimLog GaimLog;
  36. typedef struct _GaimLogLogger GaimLogLogger;
  37.  
  38. typedef enum {
  39.     GAIM_LOG_IM,
  40.     GAIM_LOG_CHAT,
  41.     GAIM_LOG_SYSTEM,
  42. } GaimLogType;
  43.  
  44. typedef enum {
  45.     GAIM_LOG_READ_NO_NEWLINE = 1,
  46. } GaimLogReadFlags;
  47.  
  48. #include "account.h"
  49. #include "conversation.h"
  50.  
  51. /**
  52.  * A log logger.
  53.  *
  54.  * This struct gets filled out and is included in the GaimLog.  It contains everything
  55.  * needed to write and read from logs.
  56.  */
  57. /*@{*/
  58. struct _GaimLogLogger {
  59.     char *name;               /**< The logger's name */
  60.     char *id;                 /**< an identifier to refer to this logger */
  61.  
  62.     /** This gets called when the log is first created.
  63.         I don't think this is actually needed. */
  64.     void(*create)(GaimLog *log);
  65.  
  66.     /** This is used to write to the log file */
  67.     void(*write)(GaimLog *log,
  68.              GaimMessageFlags type,
  69.              const char *from,
  70.              time_t time,
  71.              const char *message);
  72.  
  73.     /** Called when the log is destroyed */
  74.     void (*finalize)(GaimLog *log);
  75.  
  76.     /** This function returns a sorted GList of available GaimLogs */
  77.     GList *(*list)(GaimLogType type, const char *name, GaimAccount *account);
  78.  
  79.     /** Given one of the logs returned by the logger's list function,
  80.      * this returns the contents of the log in GtkIMHtml markup */
  81.     char *(*read)(GaimLog *log, GaimLogReadFlags *flags);
  82.     
  83.     /** Given one of the logs returned by the logger's list function,
  84.      * this returns the size of the log in bytes */
  85.     int (*size)(GaimLog *log);
  86.  
  87.     /** Returns the total size of all the logs. If this is undefined a default
  88.      * implementation is used */
  89.     int (*total_size)(GaimLogType type, const char *name, GaimAccount *account);
  90.  
  91.     /** This function returns a sorted GList of available system GaimLogs */
  92.     GList *(*list_syslog)(GaimAccount *account);
  93. };
  94.  
  95. /**
  96.  * A log.  Not the wooden type.
  97.  */
  98. struct _GaimLog {
  99.     GaimLogType type;                     /**< The type of log this is */
  100.     char *name;                           /**< The name of this log */
  101.     GaimAccount *account;                 /**< The account this log is taking
  102.                                                place on */
  103.     time_t time;                          /**< The time this conversation
  104.                                                started */
  105.     GaimLogLogger *logger;                /**< The logging mechanism this log
  106.                                                is to use */
  107.     void *logger_data;                    /**< Data used by the log logger */
  108. };
  109.  
  110.  
  111. #ifdef __cplusplus
  112. extern "C" {
  113. #endif
  114.  
  115.     /***************************************
  116.      ** LOG FUNCTIONS **********************
  117.      ***************************************/
  118.  
  119.     /**
  120.      * Creates a new log
  121.      *
  122.      * @param type        The type of log this is.
  123.      * @param name        The name of this conversation (Screenname, chat name,
  124.      *                    etc.)
  125.      * @param account     The account the conversation is occurring on
  126.      * @param time        The time this conversation started
  127.      * @return            The new log
  128.      */
  129.     GaimLog *gaim_log_new(GaimLogType type, const char *name,
  130.             GaimAccount *account, time_t time);
  131.  
  132.     /**
  133.      * Frees a log
  134.      *
  135.      * @param log         The log to destroy
  136.      */
  137.     void gaim_log_free(GaimLog *log);
  138.  
  139.     /**
  140.      * Writes to a log file. Assumes you have already checked if logging is appropriate.
  141.      *
  142.      * @param log          The log to write to
  143.      * @param type         The type of message being logged
  144.      * @param from         Whom this message is coming from, or NULL for
  145.      *                     system messages
  146.      * @param time         A timestamp in UNIX time
  147.      * @param message      The message to log
  148.      */
  149.     void gaim_log_write(GaimLog *log,
  150.                 GaimMessageFlags type,
  151.                 const char *from,
  152.                 time_t time,
  153.                 const char *message);
  154.  
  155.     /**
  156.      * Reads from a log
  157.      *
  158.      * @param log   The log to read from
  159.      * @param flags The returned logging flags.
  160.      *
  161.      * @return The contents of this log in Gaim Markup.
  162.      */
  163.     char *gaim_log_read(GaimLog *log, GaimLogReadFlags *flags);
  164.  
  165.     /**
  166.      * Returns a list of all available logs
  167.      *
  168.      * @param type                The type of the log
  169.      * @param name                The name of the log
  170.      * @param account             The account
  171.      * @return                    A sorted list of GaimLogs
  172.      */
  173.     GList *gaim_log_get_logs(GaimLogType type, const char *name, GaimAccount *account);
  174.  
  175.     /**
  176.      * Returns a list of all available system logs
  177.      *
  178.      * @param account The account
  179.      * @return        A sorted list of GaimLogs
  180.      */
  181.     GList *gaim_log_get_system_logs(GaimAccount *account);
  182.  
  183.     /**
  184.      * Returns the size of a log 
  185.      *
  186.      * @param log                 The log
  187.      * @return                    The size of the log, in bytes
  188.      */
  189.     int gaim_log_get_size(GaimLog *log);
  190.  
  191.     /**
  192.      * Returns the size, in bytes, of all available logs in this conversation
  193.      *
  194.      * @param type                The type of the log
  195.      * @param name                The name of the log
  196.      * @param account             The account
  197.      * @return                    The size in bytes
  198.      */
  199.      int gaim_log_get_total_size(GaimLogType type, const char *name, GaimAccount *account);
  200.  
  201.     /**
  202.      * Implements GCompareFunc
  203.      *
  204.      * @param y                   A GaimLog
  205.      * @param z                   Another GaimLog
  206.      * @return                    A value as specified by GCompareFunc
  207.      */
  208.      gint gaim_log_compare(gconstpointer y, gconstpointer z);
  209.  
  210.     /******************************************
  211.      ** LOGGER FUNCTIONS **********************
  212.      ******************************************/
  213.  
  214.     /**
  215.      * Creates a new logger
  216.      *
  217.      * @param create   The logger's new function.
  218.      * @param write    The logger's write function.
  219.      * @param finalize The logger's finalize function.
  220.      * @param list     The logger's list function.
  221.      * @param read     The logger's read function.
  222.      * @param size     The logger's size function.
  223.      *
  224.      * @return The new logger
  225.      */
  226.     GaimLogLogger *gaim_log_logger_new(
  227.                     void(*create)(GaimLog *),
  228.                     void(*write)(GaimLog *, GaimMessageFlags, const char *, time_t, const char *),
  229.                     void(*finalize)(GaimLog *),
  230.                     GList*(*list)(GaimLogType type, const char*, GaimAccount*),
  231.                     char*(*read)(GaimLog*, GaimLogReadFlags*),
  232.                     int(*size)(GaimLog*));
  233.     /**
  234.      * Frees a logger
  235.      *
  236.      * @param logger       The logger to free
  237.      */
  238.     void gaim_log_logger_free(GaimLogLogger *logger);
  239.  
  240.     /**
  241.      * Adds a new logger
  242.      *
  243.      * @param logger       The new logger to add
  244.      */
  245.     void gaim_log_logger_add (GaimLogLogger *logger);
  246.  
  247.     /**
  248.      *
  249.      * Removes a logger
  250.      *
  251.      * @param logger       The logger to remove
  252.      */
  253.     void gaim_log_logger_remove (GaimLogLogger *logger);
  254.  
  255.     /**
  256.      *
  257.      * Sets the current logger
  258.      *
  259.      * @param logger       The logger to set
  260.      */
  261.     void gaim_log_logger_set (GaimLogLogger *logger);
  262.  
  263.     /**
  264.      *
  265.      * Returns the current logger
  266.      *
  267.      * @return logger      The current logger
  268.      */
  269.     GaimLogLogger *gaim_log_logger_get (void);
  270.  
  271.     /**
  272.      * Returns a GList containing the IDs and Names of the registered log
  273.      * loggers.
  274.      *
  275.      * @return The list of IDs and names.
  276.      */
  277.     GList *gaim_log_logger_get_options(void);
  278.  
  279.     void gaim_log_init(void);
  280. /*@}*/
  281.  
  282.  
  283. #ifdef __cplusplus
  284. }
  285. #endif
  286.  
  287. #endif /* _GAIM_LOG_H_ */
  288.